This document is intended for EV plug-in developers who are interested in the EV Plug-In Auditor's ability to adjust its behavior toward certain plug-ins. If you're interested, read on:
How the Auditor Works
The auditor essentially identifies two types of conflicts: conflicts where two plug-ins modify the same resource, and conflicts where a plug-in modifies a resource to which another plug-in's resources point. In order to compare resource forks efficiently, the auditor prepares a list of resources for each individual plug-in. This file list contains forty sub-lists, two for each of the twenty resource/data types the auditor checks. One of these two lists is a list of the resource IDs of that resource type that are modified by the plug-in (i.e. are actually in the plug-in file). The second list contains the resource IDs of resources that are referred to by the plug-in; for instance, if a mission points to dude resource 130, it effectively refers to a dude resource that it assumes to be unmodified. So, there's a "resources that have been modified" list and a "resources that must not be modified by other plug-ins" list. For each of the resources EV uses, there are two lists like those mentioned above that contain the appropriate IDs for each resource/conflict type.
The auditor then checks each plug-in's lists with those of the plug-ins that were loaded before it (i.e. come before it in the alphabet). This imitates EV's method of loading plug-ins, so the reports the auditor generates describe what would actually happen if you were to launch EV. (Plus, it was easier to code this way. :-) )
Here's Where You Come In
You, the plug-in developer, have the ability to make your own lists to override those generated by the auditor. This allows you complete control over how the auditor behaves toward your plug-in, simply because you can lie to the auditor about what resources you plug-in contains/needs. (Please don't abuse this feature and make your plug-in invisible to the auditor, as users probably won't like this at all!)
You can make lists to override those automatically generated by the auditor by making resources of type 'lïst' in your plug-in file itself. They're much like 'STR#'s; the 'lïst' resources contain two bytes identifying the amount of entries in the list, followed by the set of entries. If you use the TMPL file included with this document to make 'lïst' editing exactly like 'STR#' editing, where cmd-K is used to make a new entry, blah, blah blah. As long as you have a resource file with the TMPL open in ResEdit, you'll see the enhanced 'lïst' editor in ResEdit. (Put the TMPL in your ResEdit Preferences file to have it open all the time.)
The 'lïst' resources from 200 to 219 describe the resources that are modified by your plug-in, while 'lïst' resources 300 to 319 describe the resources required by your plug-in. To see exactly what number corresponds to what resource type, check out the pseudo-example in the file with the TMPLs. The first 'lïst' resource, number 128, is another index describing which 'lïst' files are to be loaded from the plug-in. If you wanted to make your own 'lïst' resource 205, you'd have to make the desired list with an ID 205, and then make an entry in resource 128 with the number 205. The auditor looks at resource 128 (if it's there) to decide which 'lïst's to load from the plug-in and which to generate independently.
Here's an example of how you would use this feature. Say your plug-in depends on the existence of the Rebel Alien missions in the original EV Data file ('mïsn's 184-189). Make a 'lïst' resource with ID 305, corresponding to missions that are required to be unmodified. Make six entries, with the numbers 184, 185, 186, 187, 188, and 189. Then make a 'lïst' resource with ID 128 (the manual override flags list), and create a single entry with the number 305, telling the auditor to use your custom list instead of generating its own. Note, however, that if other parts of your plug-in refer to other missions, you'll have to include those mission IDs in your ID 305 resource as well, because now that you've overridden the auditor's own 'lïst' generator, it's not going to be able to help you out at all.
Here's another example. Say you're making a scenario that involves multiple plug-ins, which, naturally, refer to one another. Assume system 251 (in file 1) refers to dude 201 (in file 2). The auditor would detect a conflict here, because the dude to which file 1 points is modified by file 2 (keep in mind the auditor assumes that they aren't part of the same set). To avoid this problem, add a 'lïst' resource with ID 301 (for dudes that are required to be unmodified), and leave it empty. Then make a 'lïst' resource with ID 128 (again, the manual override flags), containing one entry... you guessed it! "313" Now, the auditor uses list 301 to decide which dudes are required to be unmodified for this plug-in to operate, which is, according to your custom resource, none. Now your plug-in won't generate a conflict with the other parts of its scenario. If yet another plug-in were to modify the dude resource, you'd still be OK, because the auditor would find a conflict between file 2 and the other plug-in. This technique of overriding the auditor's conflict checking will be useful for those who want to use the so-called "Stormbringer" plug-in creation conventions, but please don't abuse this feature! If it is appropriate for the auditor to find a conflict for a certain resource and ID, by all means, let it do so!
Note that all resource-related 'lïst's (that is, 200-218 and 300-318) work in a similar fashion. The last two, 219 and 319, refer to mission bits, which act in a mostly-similar manner. List 319 contains mission bits that your plug-in's resources check (e.g. missions' AvailBitSet field, or any of the numerous MissionBit fields elsewhere in the data file), while list 219 contains mission bits whose value your plug-in changes (more specifically, the CompBitSet, CompBitSet2, and FailBitSet fields).
If you have any more questions about how this works, feel free to write me at <afn02635@afn.org>, or, if you think others would benefit from your question and its answer, post to the delta_v mailing list that Ambrosia Software has set up (to sign up, go to their Web site at <http://www.AmbrosiaSW.com/>).
